Inside Macintosh: Memory
Previous | Chapter Top | Chapter Contents | Next |
The Memory Manager provides four routines to test how much memory is available, one routine used after memory operations to determine if an error occurred, and one routine to determine the location in memory of the top of your application's partition.
To determine the total amount of free space in the current heap zone or the size of the maximum block that could be obtained after compacting the heap, use the FreeMem and MaxBlock functions, respectively. To determine what those values would be after a purge of the heap zone, call the PurgeSpace procedure. Finally, to find out how much your stack can grow before it collides with the heap, use the StackSpace function.
To find out whether a Memory Manager operation finished successfully, use the MemError function.
By calling the FreeMem function, you can find out the total amount of free space, in bytes, in the current heap zone.
FUNCTION FreeMem: LongInt;
The FreeMem function returns the total amount of free space (in bytes) in the current heap zone. Note that it usually isn't possible to allocate a block of that size, because of heap fragmentation due to nonrelocatable or locked blocks.
Even though FreeMem does not move or purge memory, you should not call it at interrupt time because the heap might be in an inconsistent state.
The registers on exit for FreeMem are
The FreeMem function reports the number of free bytes in the current heap zone. If you want to know how many bytes are available in the system heap zone rather than in the current heap zone, set bit 10 of the routine trap word. In most development systems, you can do this by supplying the word SYS as the second argument to the routine macro, as follows:
_FreeMem ,SYS
To determine how much free space remains in the system heap zone, use the FreeMemSys function.
FUNCTION FreeMemSys: LongInt;
Use the MaxBlock function to determine the size of the largest block you could allocate in the current heap zone after a compaction.
FUNCTION MaxBlock: LongInt;
The MaxBlock function returns the maximum contiguous space, in bytes, that you could obtain after compacting the current heap zone. MaxBlock does not actually do the compaction.
The registers on exit for MaxBlock are
If you want to know the size of the largest allocatable block in the system heap zone, rather than in the current heap zone, set bit 10 of the routine trap word. In most development systems, you can do this by supplying the word SYS as the second argument to the routine macro, as follows:
_MaxBlock ,SYS
Use the MaxBlockSys function to determine the size of the largest block you could allocate in the system heap after a compaction.
FUNCTION MaxBlockSys: LongInt;
Use the PurgeSpace procedure to determine the total amount of free memory and the size of the largest allocatable block after a purge of the heap.
PROCEDURE PurgeSpace (VAR total: LongInt; VAR contig: LongInt);
The PurgeSpace procedure returns, in the total parameter, the total amount of space (in bytes) that could be obtained after a general purge of the current heap zone; this amount includes space that is already free. In the contig parameter, PurgeSpace returns the size of the largest allocatable block in the current heap zone that could be obtained after a purge of the zone.
The PurgeSpace procedure does not actually purge the current heap zone.
The registers on exit for PurgeSpace are
If you want to test the system heap zone instead of the current zone, set bit 10 of the routine trap word. In most development systems, you can do this by supplying the word SYS as the second argument to the routine macro, as follows:
_PurgeSpace ,SYS
Use the StackSpace function to find out how much space there is between the bottom of the stack and the top of the application heap.
FUNCTION StackSpace: LongInt;
The StackSpace function returns the current amount of stack space (in bytes) between the current stack pointer and the application heap at the instant of return from the trap.
Ordinarily, you determine the maximum amount of stack space you need before you ship your application. In general, therefore, this routine is useful only during debugging to determine how big to make the stack. However, if your application calls a recursive function that conceivably could call itself many times, that function should keep track of the stack space and take appropriate action if it becomes too low.
To find out whether your application's last direct call to a Memory Manager routine executed successfully, use the MemError function.
FUNCTION MemError: OSErr;
The MemError function returns the result code produced by the last Memory Manager routine your application called directly.
This function is useful during application debugging. You might also use the function as one part of a memory-management scheme to identify instances in which the Memory Manager rejects overly large memory requests by returning the error code memFullErr .
Do not rely on the MemError function as the only component of a memory-management scheme. For example, suppose you call NewHandle or NewPtr and receive the result code noErr , indicating that the Memory Manager was able to allocate sufficient memory. In this case, you have no guarantee that the allocation did not deplete your application's memory reserves to levels so low that simple operations might cause your application to crash. Instead of relying on MemError , check before making a memory request that there is enough memory both to fulfill the request and to support essential operations.
Because most Memory Manager routines return a result code in register D0, you do not ordinarily need to call the MemError function if you program in assembly language. See the description of an individual routine to find out whether it returns a result code in register D0. If not, you can examine the global variable MemErr . When MemError returns, register D0 contains the result code.